abortable-iterator

abortable-iterator

Make any iterator or iterable abortable via an AbortSignal

About

Example

import { abortableSource } from 'abortable-iterator'

async function main () {
  // An example function that creates an async iterator that yields an increasing
  // number every x milliseconds and NEVER ENDS!
  const asyncCounter = async function * (start, delay) {
    let i = start
    while (true) {
      yield new Promise(resolve => setTimeout(() => resolve(i++), delay))
    }
  }

  // Create a counter that'll yield numbers from 0 upwards every second
  const everySecond = asyncCounter(0, 1000)

  // Make everySecond abortable!
  const controller = new AbortController()
  const abortableEverySecond = abortableSource(everySecond, controller.signal)

  // Abort after 5 seconds
  setTimeout(() => controller.abort(), 5000)

  try {
    // Start the iteration, which will throw after 5 seconds when it is aborted
    for await (const n of abortableEverySecond) {
      console.log(n)
    }
  } catch (err) {
    if (err.code === 'ERR_ABORTED') {
      // Expected - all ok :D
    } else {
      throw err
    }
  }
}

main()

Install

$ npm i abortable-iterator

Browser <script> tag

Loading this module through a script tag will make its exports available as AbortableIterator in the global namespace.

<script src="https://unpkg.com/abortable-iterator/dist/index.min.js"></script>

API

import {
  abortableSource,
  abortableSink,
  abortableTransform,
  abortableDuplex
} from 'abortable-iterator'

• abortableSource(source, signal, [options])
• abortableSink(sink, signal, [options])
• abortableTransform(transform, signal, [options])
• abortableDuplex(duplex, signal, [options])

abortableSource(source, signal, [options])

(alias for abortable.source(source, signal, [options]))

Make any iterator or iterable abortable via an AbortSignal.

Parameters

Name	Type	Description
source	Iterable|Iterator	The iterator or iterable object to make abortable
signal	AbortSignal	Signal obtained from AbortController.signal which is used to abort the iterator.
options	Object	(optional) options
options.onAbort	Function	An (async) function called when the iterator is being aborted, before the abort error is thrown. Default null
options.abortMessage	String	The message that the error will have if the iterator is aborted. Default "The operation was aborted"
options.abortCode	String|Number	The value assigned to the code property of the error that is thrown if the iterator is aborted. Default "ABORT_ERR"
options.returnOnAbort	Boolean	Instead of throwing the abort error, just return from iterating over the source stream.
options.onReturnError	Function	When a generator is aborted, we call .return on it - if this function errors the error value will be passed to the .onReturnError callback if passed. Default null

Returns

Type	Description
Iterable	An iterator that wraps the passed source parameter that makes it abortable via the passed signal parameter.

The returned iterator will throw an AbortError when it is aborted that has a type with the value aborted and code property with the value ABORT_ERR by default.

abortableSink(sink, signal, [options])

The same as abortable.source except this makes the passed sink abortable. Returns a new sink that wraps the passed sink and makes it abortable via the passed signal parameter.

abortableTransform(transform, signal, [options])

The same as abortable.source except this makes the passed transform abortable. Returns a new transform that wraps the passed transform and makes it abortable via the passed signal parameter.

abortableDuplex(duplex, signal, [options])

The same as abortable.source except this makes the passed duplex abortable. Returns a new duplex that wraps the passed duplex and makes it abortable via the passed signal parameter.

Note that this will abort both sides of the duplex. Use duplex.sink = abortable.sink(duplex.sink) or duplex.source = abortable.source(duplex.source) to abort just the sink or the source.

Related

• it-pipe Utility to "pipe" async iterables together

API Docs

• https://alanshaw.github.io/abortable-iterator

License

Licensed under either of

• Apache 2.0, (LICENSE-APACHE / http://www.apache.org/licenses/LICENSE-2.0)
• MIT (LICENSE-MIT / http://opensource.org/licenses/MIT)

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Changelog

5.1.0 (2024-08-07)

Features

• add abortName option to override thrown error name (#98) (e43efdf)

Bug Fixes

• update project config (#99) (c6660f5)

Trivial Changes

• add or force update .github/workflows/js-test-and-release.yml (#95) (b4aeafa)
• delete templates [skip ci] (#94) (be4d6bb)

Dependencies

• dev: bump aegir from 38.1.8 to 44.1.0 (#97) (8dd8a87)
• dev: bump delay from 5.0.0 to 6.0.0 (#89) (e06ec34)